Skunkware 5/Skunkware 5.iso/man/cat.1/gpic.1

Text File | 1995-07-25 | 27KB | 529 lines

     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



     NNNNAAAAMMMMEEEE
          gpic - compile pictures for troff or TeX

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          ggggppppiiiicccc [ ----nnnnvvvvCCCC ] [ _f_i_l_e_n_a_m_e ...  ]
          ggggppppiiiicccc ----tttt [ ----ccccvvvvzzzzCCCC ] [ _f_i_l_e_n_a_m_e ...  ]

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          This manual page describes the GNU version of ppppiiiicccc, which is
          part of the groff document formatting system.  ppppiiiicccc compiles
          descriptions of pictures embedded within ttttrrrrooooffffffff or TeX input
          files into commands that are understood by TeX or ttttrrrrooooffffffff.
          Each picture starts with a line beginning with ....PPPPSSSS and ends
          with a line beginning with ....PPPPEEEE.  Anything outside of ....PPPPSSSS and
          ....PPPPEEEE is passed through without change.

          It is the user's responsibility to provide appropriate
          definitions of the PPPPSSSS and PPPPEEEE macros.  When the macro package
          being used does not supply such definitions (for example,
          old versions of -ms), appropriate definitions can be
          obtained with ----mmmmppppiiiicccc: these will center each picture.

     OOOOPPPPTTTTIIIIOOOONNNNSSSS
          Options that do not take arguments may be grouped behind a
          single ----.  The special option -------- can be used to mark the end
          of the options.  A filename of ---- refers to the standard
          input.

          ----CCCC   Recognize ....PPPPSSSS and ....PPPPEEEE even when followed by a character
               other than space or newline.

          ----nnnn   Don't use the groff extensions to the troff drawing
               commands.  You should use this if you are using a
               postprocessor that doesn't support these extensions.
               The extensions are described in ggggrrrrooooffffffff____oooouuuutttt(5).  The ----nnnn
               option also causes pic not to use zero-length lines to
               draw dots in troff mode.

          ----tttt   TeX mode.

          ----cccc   Be more compatible with ttttppppiiiicccc.  Implies ----tttt.  Lines
               beginning with \\\\ are not passed through transparently.
               Lines beginning with .... are passed through with the
               initial .... changed to \\\\.  A line beginning with ....ppppssss is
               given special treatment: it takes an optional integer
               argument specifying the line thickness (pen size) in
               milliinches; a missing argument restores the previous
               line thickness; the default line thickness is 8
               milliinches.  The line thickness thus specified takes
               effect only when a non-negative line thickness has not
               been specified by use of the tttthhhhiiiicccckkkknnnneeeessssssss attribute or by
               setting the lllliiiinnnneeeetttthhhhiiiicccckkkk variable.



     Page 1                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



          ----vvvv   Print the version number.

          ----zzzz   In TeX mode draw dots using zero-length lines.

          The following options supported by other versions of ppppiiiicccc are
          ignored:

          ----DDDD   Draw all lines using the \D escape sequence.  ppppiiiicccc
               always does this.

          ----TTTT _d_e_v
               Generate output for the ttttrrrrooooffffffff device _d_e_v.  This is
               unnecessary because the ttttrrrrooooffffffff output generated by ppppiiiicccc
               is device-independent.

     UUUUSSSSAAAAGGGGEEEE
          This section describes only the differences between GNU pic
          and the original version of pic.  Many of these differences
          also apply to newer versions of Unix pic.

        TTTTeeeeXXXX mmmmooooddddeeee
          TeX mode is enabled by the ----tttt option.  In TeX mode, pic will
          define a vbox called \\\\ggggrrrraaaapppphhhh for each picture.  You must
          yourself print that vbox using, for example, the command

               \\\\cccceeeennnntttteeeerrrrlllliiiinnnneeee{{{{\\\\bbbbooooxxxx\\\\ggggrrrraaaapppphhhh}}}}

          Actually, since the vbox has a height of zero this will
          produce slightly more vertical space above the picture than
          below it;

               \\\\cccceeeennnntttteeeerrrrlllliiiinnnneeee{{{{\\\\rrrraaaaiiiisssseeee 1111eeeemmmm\\\\bbbbooooxxxx\\\\ggggrrrraaaapppphhhh}}}}

          would avoid this.

          You must use a TeX driver that supports the ttttppppiiiicccc specials,
          version 2.

          Lines beginning with \\\\ are passed through transparently; a %%%%
          is added to the end of the line to avoid unwanted spaces.
          You can safely use this feature to change fonts or to change
          the value of \\\\bbbbaaaasssseeeelllliiiinnnneeeesssskkkkiiiipppp.  Anything else may well produce
          undesirable results; use at your own risk.  Lines beginning
          with a period are not given any special treatment.

        CCCCoooommmmmmmmaaaannnnddddssss
          ffffoooorrrr _v_a_r_i_a_b_l_e ==== _e_x_p_r_1 ttttoooo _e_x_p_r_2 [bbbbyyyy [****]_e_x_p_r_3] ddddoooo _X _b_o_d_y _X
               Set _v_a_r_i_a_b_l_e to _e_x_p_r_1.  While the value of _v_a_r_i_a_b_l_e is
               less than or equal to _e_x_p_r_2, do _b_o_d_y and increment
               _v_a_r_i_a_b_l_e by _e_x_p_r_3; if bbbbyyyy is not given, increment
               _v_a_r_i_a_b_l_e by 1.  If _e_x_p_r_3 is prefixed by **** then _v_a_r_i_a_b_l_e
               will instead be multiplied by _e_x_p_r_3.  _X can be any



     Page 2                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



               character not occurring in _b_o_d_y.

          iiiiffff _e_x_p_r tttthhhheeeennnn _X _i_f-_t_r_u_e _X [eeeellllsssseeee _Y _i_f-_f_a_l_s_e _Y]
               Evaluate _e_x_p_r; if it is non-zero then do _i_f-_t_r_u_e,
               otherwise do _i_f-_f_a_l_s_e.  _X can be any character not
               occurring in _i_f-_t_r_u_e.  _Y can be any character not
               occurring in _i_f-_f_a_l_s_e.

          pppprrrriiiinnnntttt _a_r_g...
               Concatenate the arguments and print as a line on
               stderr.  Each _a_r_g must be an expression, a position, or
               text.  This is useful for debugging.

          ccccoooommmmmmmmaaaannnndddd _a_r_g...
               Concatenate the arguments and pass them through as a
               line to troff orTeX.  Each _a_r_g must be an expression, a
               position, or text.  This has a similar effect to a line
               beginning with .... or \\\\, but allows the values of
               variables to be passed through.

          sssshhhh _X _c_o_m_m_a_n_d _X
               Pass _c_o_m_m_a_n_d to a shell.  _X can be any character not
               occurring in _c_o_m_m_a_n_d.

          ccccooooppppyyyy """"_f_i_l_e_n_a_m_e""""
               Include _f_i_l_e_n_a_m_e at this point in the file.

          ccccooooppppyyyy [""""_f_i_l_e_n_a_m_e""""] tttthhhhrrrruuuu _X _b_o_d_y _X [uuuunnnnttttiiiillll """"_w_o_r_d""""]
          ccccooooppppyyyy [""""_f_i_l_e_n_a_m_e""""] tttthhhhrrrruuuu _m_a_c_r_o [uuuunnnnttttiiiillll """"_w_o_r_d""""]
               This construct does _b_o_d_y once for each line of
               _f_i_l_e_n_a_m_e; the line is split into blank-delimited words,
               and occurrences of $$$$_i in _b_o_d_y, for _i between 1 and 9,
               are replaced by the _i-th word of the line.  If _f_i_l_e_n_a_m_e
               is not given, lines are taken from the current input up
               to ....PPPPEEEE.  If an uuuunnnnttttiiiillll clause is specified, lines will be
               read only until a line the first word of which is _w_o_r_d;
               that line will then be discarded.  _X can be any
               character not occurring in _b_o_d_y.  For example,


                    ....PPPPSSSS
                    ccccooooppppyyyy tttthhhhrrrruuuu %%%% cccciiiirrrrcccclllleeee aaaatttt (((($$$$1111,,,,$$$$2222)))) %%%% uuuunnnnttttiiiillll """"EEEENNNNDDDD""""
                    1111 2222
                    3333 4444
                    5555 6666
                    EEEENNNNDDDD
                    bbbbooooxxxx
                    ....PPPPEEEE

               is equivalent to





     Page 3                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



                    ....PPPPSSSS
                    cccciiiirrrrcccclllleeee aaaatttt ((((1111,,,,2222))))
                    cccciiiirrrrcccclllleeee aaaatttt ((((3333,,,,4444))))
                    cccciiiirrrrcccclllleeee aaaatttt ((((5555,,,,6666))))
                    bbbbooooxxxx
                    ....PPPPEEEE

               The commands to be performed for each line can also be
               taken from a macro defined earlier by giving the name
               of the macro as the argument to tttthhhhrrrruuuu.

          rrrreeeesssseeeetttt
          rrrreeeesssseeeetttt _v_a_r_i_a_b_l_e_1,,,, _v_a_r_i_a_b_l_e_2 ...
               Reset pre-defined variables _v_a_r_i_a_b_l_e_1, _v_a_r_i_a_b_l_e_2 ... to
               their default values.  If no arguments are given, reset
               all pre-defined variables to their default values.
               Note that assigning a value to ssssccccaaaalllleeee also causes all
               pre-defined variables that control dimensions to be
               reset to their default values times the new value of
               scale.

          ppppllllooootttt _e_x_p_r [""""_t_e_x_t""""]
               This is a text object which is constructed by using
               _t_e_x_t as a format string for sprintf with an argument of
               _e_x_p_r.  If _t_e_x_t is omitted a format string of """"%%%%gggg"""" is
               used.  Attributes can be specified in the same way as
               for a normal text object.  Be very careful that you
               specify an appropriate format string; pic does only
               very limited checking of the string.  This is
               deprecated in favour of sssspppprrrriiiinnnnttttffff.

          _v_a_r_i_a_b_l_e::::====_e_x_p_r
               This is similar to ==== except _v_a_r_i_a_b_l_e must already be
               defined, and the value of _v_a_r_i_a_b_l_e will be changed only
               in the innermost block in which it is defined.  (By
               contrast, ==== defines the variable in the current block
               if it is not already defined there, and then changes
               the value in the current block.)

          Arguments of the form

               _X anything _X

          are also allowed to be of the form

               {{{{ _a_n_y_t_h_i_n_g }}}}

          In this case _a_n_y_t_h_i_n_g can contain balanced occurrences of {{{{
          and }}}}.  Strings may contain _X or imbalanced occurrences of {{{{
          and }}}}.

        EEEExxxxpppprrrreeeessssssssiiiioooonnnnssss



     PPPPaaaaggggeeee 4444                                           ((((pppprrrriiiinnnntttteeeedddd 3333////9999////99994444))))






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



          The syntax for expressions has been significantly extended:

          _x ^^^^ _y (exponentiation)
          ssssiiiinnnn((((_x))))
          ccccoooossss((((_x))))
          aaaattttaaaannnn2222((((_y,,,, _x))))
          lllloooogggg((((_x)))) (base 10)
          eeeexxxxpppp((((_x)))) (base 10, ie 10_x)
          ssssqqqqrrrrtttt((((_x))))
          iiiinnnntttt((((_x))))
          rrrraaaannnndddd(((()))) (return a random number between 0 and 1)
          rrrraaaannnndddd((((_x)))) (return a random number between 1 and _x; deprecated)
          mmmmaaaaxxxx((((_e_1,,,, _e_2))))
          mmmmiiiinnnn((((_e_1,,,, _e_2))))
          !!!!_e
          _e_1 &&&&&&&& _e_2
          _e_1 |||||||| _e_2
          _e_1 ======== _e_2
          _e_1 !!!!==== _e_2
          _e_1 >>>>==== _e_2
          _e_1 >>>> _e_2
          _e_1 <<<<==== _e_2
          _e_1 <<<< _e_2
          """"_s_t_r_1"""" ======== """"_s_t_r_2""""
          """"_s_t_r_1"""" !!!!==== """"_s_t_r_2""""

          String comparison expressions must be parenthesised in some
          contexts to avoid ambiguity.

        OOOOtttthhhheeeerrrr CCCChhhhaaaannnnggggeeeessss
          A bare expression, _e_x_p_r, is acceptable as an attribute; it
          is equivalent to _d_i_r _e_x_p_r, where _d_i_r is the current
          direction.  For example

               lllliiiinnnneeee 2222iiii

          means draw a line 2 inches long in the current direction.

          The maximum width and height of the picture are taken from
          the variables mmmmaaaaxxxxppppsssswwwwiiiidddd and mmmmaaaaxxxxppppsssshhhhtttt.  Initially these have
          values 8.5 and 11.

          Scientific notation is allowed for numbers.  For example
               xxxx ==== 5555eeee----2222

          Text attributes can be compounded.  For example,
               """"ffffoooooooo"""" aaaabbbboooovvvveeee lllljjjjuuuusssstttt
          is legal.

          There is no limit to the depth to which blocks can be
          examined.  For example,
               [[[[AAAA:::: [[[[BBBB:::: [[[[CCCC:::: bbbbooooxxxx ]]]]]]]]]]]] wwwwiiiitttthhhh ....AAAA....BBBB....CCCC....sssswwww aaaatttt 1111,,,,2222



     Page 5                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



               cccciiiirrrrcccclllleeee aaaatttt llllaaaasssstttt [[[[]]]]....AAAA....BBBB....CCCC
          is acceptable.

          Arcs now have compass points determined by the circle of
          which the arc is a part.

          Circles and arcs can be dotted or dashed.  In TeX mode
          splines can be dotted or dashed.

          Boxes can have rounded corners.  The rrrraaaadddd attribute specifies
          the radius of the quarter-circles at each corner.  If no rrrraaaadddd
          or ddddiiiiaaaammmm attribute is given, a radius of bbbbooooxxxxrrrraaaadddd is used.
          Initially, bbbbooooxxxxrrrraaaadddd has a value of 0.  A box with rounded
          corners can be dotted or dashed.

          The ....PPPPSSSS line can have a second argument specifying a maximum
          height for the picture.  If the width of zero is specified
          the width will be ignored in computing the scaling factor
          for the picture.  Note that GNU pic will always scale a
          picture by the same amount vertically as horizontally.  This
          is different from the DWB 2.0 pic which may scale a picture
          by a different amount vertically than horizontally if a
          height is specified.

          Each text object has an invisible box associated with it.
          The compass points of a text object are determined by this
          box.  The implicit motion associated with the object is also
          determined by this box.  The dimensions of this box are
          taken from the width and height attributes; if the width
          attribute is not supplied then the width will be taken to be
          tttteeeexxxxttttwwwwiiiidddd; if the height attribute is not supplied then the
          height will be taken to be the number of text strings
          associated with the object times tttteeeexxxxtttthhhhtttt.  Initially tttteeeexxxxttttwwwwiiiidddd
          and tttteeeexxxxtttthhhhtttt have a value of 0.

          In places where a quoted text string can be used, an
          expression of the form

               sssspppprrrriiiinnnnttttffff((((""""_f_o_r_m_a_t"""",,,, _a_r_g,,,,...))))

          can also be used; this will produce the arguments formatted
          according to _f_o_r_m_a_t, which should be a string as described
          in pppprrrriiiinnnnttttffff(3) appropriate for the number of arguments
          supplied, using only the eeee, ffff, gggg or %%%% format characters.

          The thickness of the lines used to draw objects is
          controlled by the lllliiiinnnneeeetttthhhhiiiicccckkkk variable.  This gives the
          thickness of lines in points.  A negative value means use
          the default thickness: in TeX output mode, this means use a
          thickness of 8 milliinches; in TeX output mode with the ----cccc
          option, this means use the line thickness specified by ....ppppssss
          lines; in troff output mode, this means use a thickness



     Page 6                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



          proportional to the pointsize.  A zero value means draw the
          thinnest possible line supported by the output device.
          Initially it has a value of -1.  There is also a tttthhhhiiiicccckkkk[nnnneeeessssssss]
          attribute.  For example,

               cccciiiirrrrcccclllleeee tttthhhhiiiicccckkkknnnneeeessssssss 1111....5555

          would draw a circle using a line with a thickness of 1.5
          points.  The thickness of lines is not affected by the value
          of the ssssccccaaaalllleeee variable, nor by the width or height given in
          the ....PPPPSSSS line.

          Boxes (including boxes with rounded corners), circles and
          ellipses can be filled by giving then an attribute of
          ffffiiiillllllll[eeeedddd].  This takes an optional argument of an expression
          with a value between 0 and 1; 0 will fill it with white, 1
          with black, values in between with a proportionally gray
          shade.  A value greater than 1 can also be used: this means
          fill with the shade of gray that is currently being used for
          text and lines.  Normally this will be black, but output
          devices may provide a mechanism for changing this.  Without
          an argument, then the value of the variable ffffiiiillllllllvvvvaaaallll will be
          used.  Initially this has a value of 0.5.  The invisible
          attribute does not affect the filling of objects.  Any text
          associated with a filled object will be added after the
          object has been filled, so that the text will not be
          obscured by the filling.

          Arrow heads will be drawn as solid triangles if the variable
          aaaarrrrrrrroooowwwwhhhheeeeaaaadddd is non-zero and either TeX mode is enabled or the
          ----xxxx option has been given.  Initially aaaarrrrrrrroooowwwwhhhheeeeaaaadddd has a value
          of 1.

          The troff output of pic is device-independent.  The ----TTTT
          option is therefore redundant.  All numbers are taken to be
          in inches; numbers are never interpreted to be in troff
          machine units.

          Objects can have an aaaalllliiiiggggnnnneeeedddd attribute.  This will only work
          when the postprocessor is ggggrrrrooooppppssss.  Any text associated with
          an object having the aaaalllliiiiggggnnnneeeedddd attribute will be rotated about
          the center of the object so that it is aligned in the
          direction from the start point to the end point of the
          object.  Note that this attribute will have no effect for
          objects whose start and end points are coincident.

          In places where _ntttthhhh is allowed ````_e_x_p_r''''tttthhhh is also allowed.
          Note that ''''tttthhhh is a single token: no space is allowed between
          the '''' and the tttthhhh.  For example,


               ffffoooorrrr iiii ==== 1111 ttttoooo 4444 ddddoooo {{{{



     Page 7                                           (printed 3/9/94)






     GGGGPPPPIIIICCCC((((1111))))       GGGGrrrrooooffffffff VVVVeeeerrrrssssiiiioooonnnn 1111....00009999 ((((22224444 FFFFeeeebbbbrrrruuuuaaaarrrryyyy 1111999999994444))))       GGGGPPPPIIIICCCC((((1111))))



                  line from `i'th box.nw to `i+1'th box.se
               }

     FFFFIIIILLLLEEEESSSS
          ////uuuussssrrrr////llllooooccccaaaallll////lllliiiibbbb////ggggrrrrooooffffffff////ttttmmmmaaaacccc////ttttmmmmaaaacccc....ppppiiiicccc
               Example definitions of the PPPPSSSS and PPPPEEEE macros.

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
          ggggttttrrrrooooffffffff(1), ggggrrrrooooffffffff____oooouuuutttt(5), tttteeeexxxx(1)
          Tpic: Pic for TeX
          AT&T Bell Laboratories, Computing Science Technical Report
          No. 116, PIC - A Graphics Language for Typesetting.  (This
          can be obtained by sending a mail message to
          [e-mail] with a body of
          `send 116 from research/cstr'.)

     BBBBUUUUGGGGSSSS
          Input characters that are illegal for ggggrrrrooooffffffff (ie those with
          ASCII code 0 or between 013 and 037 octal or between 0200
          and 0237 octal) are rejected even in TeX mode.

          The interpretation of ffffiiiillllllllvvvvaaaallll is incompatible with the pic
          in 10th edition Unix, which interprets 0 as black and 1 as
          white.































     Page 8                                           (printed 3/9/94)